.\" This file is generated automatically by convert.pl from gtags/manual.in.
.TH GTAGS 1 "May 2012" "GNU Project"
.SH NAME
gtags \- create tag files for global.
.SH SYNOPSIS
\fBgtags\fP [-ciIOqvw][-d \fItag-file\fP][-f \fIfile\fP][\fIdbpath\fP]
.br
.SH DESCRIPTION
\fBGtags\fP is used to create tag files for \fBglobal\fP(1).
.PP
\fBGtags\fP recursively collects source files under the current directory,
pickup symbols and write the cross-reference data into the tag files
(\'GTAGS\', \'GRTAGS\' and \'GPATH\').
.PP
If \'gtags.files\' exists or the \fB-f\fP option is specified,
target files are limited by it. Lines starting with ". " are comments.
.PP
C, yacc, Assembly, Java, C++ and PHP source files are supported.
Files whose names end in \'.c\', \'.h\' are assumed to be C source files.
Files whose names end in \'.y\' are assumed to be yacc source files.
Files whose names end in \'.s\', \'.S\' are assumed to be Assembly source files.
Files whose names end in \'.java\' are assumed to be Java source files.
Files whose names end in \'.c++\', \'.cc\', \'.hh\', \'.cpp\', \'.cxx\', \'.hxx\', \'.hpp\', \'.C\', \'.H\' are assumed to be C++ source files.
Files whose names end in \'.php\', \'.php3\', \'.phtml\' are assumed to be PHP source files.
Other files are assumed to be text files.
.SH OPTIONS
The following options are available:
.TP
\fB--accept-dotfiles\fP
Accept dot files and dot directories. By default, \fBgtags\fP ignore them.
.TP
\fB-c\fP, \fB--compact\fP
Make GTAGS in compact format.
This option does not influence GRTAGS,
because they are always made in compact format.
.TP
\fB--config\fP[=\fIname\fP]
Print the value of config variable \fIname\fP.
If \fIname\fP is not specified then print all names and values.
.TP
\fB-d\fP, \fB--dump\fP \fItag-file\fP
Dump a tag file. The output format is 'key<tab>data'.
This is for debugging.
.TP
\fB-f\fP, \fB--file\fP \fIfile\fP
Browse through all source files whose names are listed in \fIfile\fP.
The argument \fIfile\fP can  be set to \'-\' to accept a list of
files from the standard input.
File names must be separated by newline.
.TP
\fB--gtagsconf\fP \fIfile\fP
Set the \fBGTAGSCONF\fP environment variable to \fIfile\fP.
.TP
\fB--gtagslabel\fP \fIlabel\fP
Set the \fBGTAGSLABEL\fP environment variable to \fIlabel\fP.
.TP
\fB-I\fP, \fB--idutils\fP
Also make the ID database file for \fBidutils\fP(1).
.TP
\fB-i\fP, \fB--incremental\fP
Update tag files incrementally. You had better use
\fBglobal\fP(1) with the -u option.
.TP
\fB-O\fP, \fB--objdir\fP
Use BSD-style objdir as the location of tag files.
If \'$MAKEOBJDIRPREFIX\' directory exists, \fBgtags\fP creates
\'$MAKEOBJDIRPREFIX/<current directory>\' directory and makes
tag files in it.
If \fIdbpath\fP is specified, this option is ignored.
.TP
\fB--single-update\fP \fIfile\fP
Update tag files for single file.
It is considered that \fIfile\fP was added or updated,
and there is no change in other files.
This option implies the -i option.
.TP
\fB--statistics\fP
Print statistics information.
.TP
\fB-q\fP, \fB--quiet\fP
Quiet mode.
.TP
\fB-v\fP, \fB--verbose\fP
Verbose mode.
.TP
\fB-w\fP, \fB--warning\fP
Print warning messages.
.TP
\fIdbpath\fP
The directory in which tag files are generated.
The default is the current directory.
.SH EXAMPLES
.nf
$ ls -F
Makefile      src/    lib/
$ gtags -v
$ global -x main
main              10 src/main.c  main (argc, argv) {
.fi
.SH FILES
.TP
\'GTAGS\'
Tag file for object definitions.
.TP
\'GRTAGS\'
Tag file for object references.
.TP
\'GPATH\'
Tag file for path names.
.TP
\'$HOME/.globalrc\', \'/etc/gtags.conf\', \'[sysconfdir]/gtags.conf\'
Configuration files.
.TP
\'gtags.files\'
The list of candidates of target files.
.SH ENVIRONMENT
The following environment variables affect the execution of \fBgtags\fP:
.TP
\fBTMPDIR\fP
The location used to stored temporary files. The default is \'/tmp\'.
.TP
\fBGTAGSCONF\fP
Configuration file. The default is \'$HOME/.globalrc\'.
.TP
\fBGTAGSLABEL\fP
Configuration label. The default is \fIdefault\fP.
.TP
\fBGTAGSCACHE\fP
The size of B-tree cache. The default is 50000000 (bytes).
.TP
\fBGTAGSFORCECPP\fP
If this variable is set, each file whose suffix is 'h' is treated
as a C++ source file.
.TP
\fBMAKEOBJDIRPREFIX\fP
If this variable is set, \'$MAKEOBJDIRPREFIX\' is used as the prefix
of BSD-style objdir. The default is \'/usr/obj\'.
.SH CONFIGURATION
The following configuration variables affect the execution of \fBgtags\fP.
You can see the default value for each variable with the \fB--config\fP option.
.TP
icase_path(boolean)
Ignore case distinctions in the path.
Suffixes check is affected by this capability.
.TP
langmap(comma separated list)
Language mapping. Each comma-separated map consists of
the language name, a colon, and a list of file extensions.
As a special exception, \fBgtags\fP collects values from multiple langmap variables.
Default mapping is 'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.
.TP
gtags_parser(comma separated list)
Specify the mapping of language names and plugin parsers.
Each part delimited by the comma consists of the language name, a colon,
the shared object path, an optional colon followed by a function name.
If the function name is not specified, 'parser' is assumed.
As a special exception, \fBgtags\fP collects values from multiple gtags_parser variables.
.TP
skip(comma separated list)
\fBGtags\fP skips files which are listed in this list.
As a special exception, \fBgtags\fP collects values from multiple skip variables.
If the value ends with '/', it is assumed as a directory and \fBgtags\fP skips all files under it.
If the value starts with '/', it is assumed a relative path from the root of source directory.
.SH DIAGNOSTICS
\fBGtags\fP exits with a non 0 value if an error occurred, 0 otherwise.
.SH "SEE ALSO"
\fBglobal\fP(1),
\fBhtags\fP(1).
.PP
GNU GLOBAL source code tag system
.br
(http://www.gnu.org/software/global/).
.SH BUG
\'GTAGS\' and \'GRTAGS\' are very large.
In advance of using this command, check the space of your disk.
.PP
Assembly support is far from complete.
It extracts only ENTRY() and ALTENTRY() from source file.
Probably valid only for FreeBSD and Linux kernel source.
.PP
There is no concurrency control about tag files.
.SH AUTHOR
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
.SH HISTORY
The \fBgtags\fP command appeared in FreeBSD 2.2.2.
